#####################################################################
# Product:      KnowledgeEngine (Plone Edition)
#
# File:         Wizard.py
#
# Copyright:    Copyright (c) 2005, Faulkner Technologies
#
# Author:       Brian Oliver
#
# Description:  Wizards provide a basic mechanism for managing
#               the step-wise collection of properties for things like
#               Reports and Accessories followed by the execution of
#               some algorithm with the collected properties.
#
#               Wizards make use of the Property management system
#
# See Also:     WizardState, PropertyReflection, PropertyDefinition, 
#               PropertyAccess, Accessory 
#####################################################################

#####################################################################
## KnowledgeEngine Library Imports
from Common import *

#####################################################################
## Zope Library Imports
from Globals import InitializeClass
from AccessControl import ClassSecurityInfo
from AccessControl.Role import RoleManager
 
#####################################################################
## Python Library Imports
# (none)

#####################################################################
## Wizard Interface Definition
class Wizard(RoleManager):
    """
        An interface specifying how to manage a collection of 
        paged / step-wise properties to edit/display
    """

    #---------------------------------------------------------------#

    #define security
    security = ClassSecurityInfo()
    security.declareObjectPublic()
    security.setDefaultAccess("allow")
        
    #---------------------------------------------------------------#
        
    def getTotalWizardSteps(self, wizardState, context=None):
        """
            ABSTRACT: Returns the number of wizard steps 
            given the specified wizardState.
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions
            
            NOTE: Step 1 is the first step!

            RETURN: Integer
        """
        
        #this method should be overridden to provide the actual number
        return 0

    #---------------------------------------------------------------#
        
    def getCurrentWizardStep(self, wizardState):
        """
            FINAL: Returns the current wizard step from the specified
            wizard state.
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions
            
            NOTE: Step 1 is the first step!            

            RETURN: Integer
        """
        
        return wizardState.getCurrentWizardStep()

    #---------------------------------------------------------------#

    def getWizardStepTitle(self, wizardState, context=None):
        """
            Return the title of the specified wizard step
            using the provided wizard state.
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions
            
            By default returns 'Step # of #'.  Override this
            method if you'd like something else.

            RETURN: String
        """            
        
        #the numer of wizard steps
        totalWizardSteps = self.getTotalWizardSteps(wizardState, context)
        
        if totalWizardSteps > 1:
            return "Wizard Step %d of %d" % (self.getCurrentWizardStep(wizardState), totalWizardSteps)
        else:
            return "Wizard"

    #---------------------------------------------------------------#

    def getWizardStepFinishButtonTitle(self, wizardState, context=None):
        """
            Return the title of the finished button for the
            wizard step using the provided wizard state.
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions
            
            By default returns 'Finish...'.  Override this
            method if you'd like something else.

            RETURN: String
        """            
        
        return "Apply..."
        
    #---------------------------------------------------------------#
        
    def getWizardStepDescription(self, wizardState, context=None):
        """
            ABSTRACT: Returns the description of the specified wizard step
            using the provided wizard state.
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions

            RETURN: String
        """
        
        return ""
        
    #---------------------------------------------------------------#
        
    def isAtFirstWizardStep(self, wizardState, context=None):
        """
            Returns if the specified wizard state is at the first step
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions
            
            NOTE: Step 1 is the first step!            

            RETURN: Boolean
        """            

        return wizardState.getCurrentWizardStep() == 1      
        
    #---------------------------------------------------------------#
        
    def isAtLastWizardStep(self, wizardState, context=None):
        """
            Returns if the specified wizard state is at the last step
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions
            
            NOTE: Step 1 is the first step!            

            RETURN: Boolean
        """            

        return wizardState.getCurrentWizardStep() == self.getTotalWizardSteps(wizardState, context)      
        
    #---------------------------------------------------------------#
        
    def getPropertyDefinitionsForWizard(self, wizardState, context=None):
        """
            ABSTRACT: Returns a list of all PropertyDefinitions for 
            the wizard using the provided wizardState (if necessary)
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions
            
            RETURN: [PropertyDefinition]
        """            
        
        return []
        
    #---------------------------------------------------------------#
        
    def getPropertyDefinitionsForWizardStep(self, wizardState, context=None):
        """
            ABSTRACT: Returns a list of PropertyDefinitions for the specified
            wizard step using the provided wizardState (if necessary)
            
            PARAMS:
            wizardState - the current properties of the wizard in action
            context - usually a GenericObject instance that may 
                      be used to dynamically determine wizard
                      step definitions
            
            RETURN: [PropertyDefinition]
        """            
        
        return []
        
    #---------------------------------------------------------------#

#####################################################################
## Class Initialisation
InitializeClass(Wizard)
